<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Using SSL in Twisted</title>
  </head>
  <body>
    <h1>Using SSL in Twisted</h1>
    
    <h2>Overview</h2>

    <p>This document describes how to use SSL in Twisted servers and clients. It
    assumes that you know what SSL is, what some of the major reasons to use it
    are, and how to generate your own SSL certificates, in particular self-signed
    certificates. It also assumes that you are comfortable with creating TCP
    servers and clients as described in the <a href="servers.xhtml">server howto
    </a> and <a href="clients.xhtml">client howto</a>. After reading this
    document you should be able to create servers and clients that can use SSL to
    encrypt their connections, switch from using an unencrypted channel to an
    encrypted one mid-connection, and require client authentication.</p>

    <p>Using SSL in Twisted requires that you have
    <a href="http://pyopenssl.sf.net">pyOpenSSL</a> installed. A quick test to
    verify that you do is to run <code>from OpenSSL import SSL</code> at a
    python prompt and not get an error.</p>

    <p>SSL connections require SSL contexts. These contexts are generated by a
    <code>ContextFactory</code> that maintains state like the SSL method, private
    key file name, and certificate file name.</p>

    <p>Instead of using listenTCP and connectTCP to create a connection, use
    <code class="API"
    base="twisted.internet.interfaces.IReactorSSL">listenSSL</code> and
    <code class="API"
    base="twisted.internet.interfaces.IReactorSSL">connectSSL</code> for a
    server and client respectively. These methods take a contextFactory as an
    additional argument.</p>

    <p>The basic server context factory is
    <code class="API">twisted.internet.ssl.ContextFactory</code>, and the basic
    client context factory is
    <code class="API">twisted.internet.ssl.ClientContextFactory</code>. They can
    be used as-is or subclassed.
    <code class="API">twisted.internet.ssl.DefaultOpenSSLContextFactory</code>
    is a convenience server class that subclasses <code>ContextFactory</code>
    and adds default parameters to the SSL handshake and connection. Another
    useful class is
    <code class="API">twisted.internet.ssl.CertificateOptions</code>; it is a
    factory for SSL context objects that lets you specify many of the common
    verification and session options so it can do the proper pyOpenSSL
    initialization for you.</p>

    <p>Those are the big immediate differences between TCP and SSL connections,
    so let's look at an example. In it and all subsequent examples it is assumed
    that keys and certificates for the server, certificate authority, and client
    should they exist live in a <i>keys/</i> subdirectory of the directory
    containing the example code, and that the certificates are self-signed.</p>

    <h2>SSL echo server and client without client authentication</h2>

    <p>Authentication and encryption are two separate parts of the SSL protocol.
    The server almost always needs a key and certificate to authenticate itself
    to the client but is usually configured to allow encrypted connections with
    unauthenticated clients who don't have certificates. This common case is
    demonstrated first by adding SSL support to the echo client and server in
    the <a href="../examples/index.html">core examples</a>.</p>

    <h3>SSL echo server</h3>

    <pre class="python">
from twisted.internet import ssl, reactor
from twisted.internet.protocol import Factory, Protocol

class Echo(Protocol):
    def dataReceived(self, data):
        """As soon as any data is received, write it back."""
        self.transport.write(data)

if __name__ == '__main__':
    factory = Factory()
    factory.protocol = Echo
    reactor.listenSSL(8000, factory,
                      ssl.DefaultOpenSSLContextFactory(
            'keys/server.key', 'keys/server.crt'))
    reactor.run()
    </pre>

    <h3>SSL echo client</h3>

    <pre class="python">
from twisted.internet import ssl, reactor
from twisted.internet.protocol import ClientFactory, Protocol

class EchoClient(Protocol):
    def connectionMade(self):
        print "hello, world"
        self.transport.write("hello, world!")

    def dataReceived(self, data):
        print "Server said:", data
        self.transport.loseConnection()

class EchoClientFactory(ClientFactory):
    protocol = EchoClient

    def clientConnectionFailed(self, connector, reason):
        print "Connection failed - goodbye!"
        reactor.stop()

    def clientConnectionLost(self, connector, reason):
        print "Connection lost - goodbye!"
        reactor.stop()

if __name__ == '__main__':
    factory = EchoClientFactory()
    reactor.connectSSL('localhost', 8000, factory, ssl.ClientContextFactory())
    reactor.run()
    </pre>

    <p>Contexts are created according to a specified method.
    <code>SSLv3_METHOD</code>, <code>SSLv23_METHOD</code>, and
    <code>TLSv1_METHOD</code> are the valid constants that represent SSL methods
    to use when creating a context object. <code>DefaultOpenSSLContextFactory</code> and
    <code>ClientContextFactory</code> default to using <code>SSL.SSLv23_METHOD</code> as their
    method, and it is compatible for communication with all the other methods
    listed above. An older method constant, <code>SSLv2_METHOD</code>, exists but
    is explicitly disallowed in both <code>DefaultOpenSSLContextFactory</code> and
    <code>ClientContextFactory</code> for being insecure by calling
    <code>set_options(SSL.OP_NO_SSLv2)</code> on their contexts. See
    <code class="API">twisted.internet.ssl</code> for additional comments.</p>

    <h2>Using startTLS</h2>

    <p>If you want to switch from unencrypted to encrypted traffic
    mid-connection, you'll need to turn on SSL with <code class="API"
    base="twisted.internet.interfaces.ITLSTransport">startTLS</code> on both
    ends of the connection at the same time via some agreed-upon signal like the
    reception of a particular message. You can readily verify the switch to an
    encrypted channel by examining the packet payloads with a tool like
    <a href="http://www.wireshark.org/">Wireshark</a>.</p>

    <h3>startTLS server</h3>

    <pre class="python">
from OpenSSL import SSL
from twisted.internet import reactor, ssl
from twisted.internet.protocol import ServerFactory
from twisted.protocols.basic import LineReceiver

class TLSServer(LineReceiver):
    def lineReceived(self, line):
        print "received: " + line

        if line == "STARTTLS":
            print "-- Switching to TLS"
            self.sendLine('READY')
            ctx = ServerTLSContext(
                privateKeyFileName='keys/server.key',
                certificateFileName='keys/server.crt',
                )
            self.transport.startTLS(ctx, self.factory)


class ServerTLSContext(ssl.DefaultOpenSSLContextFactory):
    def __init__(self, *args, **kw):
        kw['sslmethod'] = SSL.TLSv1_METHOD
        ssl.DefaultOpenSSLContextFactory.__init__(self, *args, **kw)

if __name__ == '__main__':
    factory = ServerFactory()
    factory.protocol = TLSServer
    reactor.listenTCP(8000, factory)
    reactor.run()
    </pre>

    <h3>startTLS client</h3>

    <pre class="python">
from OpenSSL import SSL
from twisted.internet import reactor, ssl
from twisted.internet.protocol import ClientFactory
from twisted.protocols.basic import LineReceiver

class ClientTLSContext(ssl.ClientContextFactory):
    isClient = 1
    def getContext(self):
        return SSL.Context(SSL.TLSv1_METHOD)

class TLSClient(LineReceiver):
    pretext = [
        "first line",
        "last thing before TLS starts",
        "STARTTLS"]

    posttext = [
        "first thing after TLS started",
        "last thing ever"]

    def connectionMade(self):
        for l in self.pretext:
            self.sendLine(l)

    def lineReceived(self, line):
        print "received: " + line
        if line == "READY":
            ctx = ClientTLSContext()
            self.transport.startTLS(ctx, self.factory)
            for l in self.posttext:
                self.sendLine(l)
            self.transport.loseConnection()

class TLSClientFactory(ClientFactory):
    protocol = TLSClient

    def clientConnectionFailed(self, connector, reason):
        print "connection failed: ", reason.getErrorMessage()
        reactor.stop()

    def clientConnectionLost(self, connector, reason):
        print "connection lost: ", reason.getErrorMessage()
        reactor.stop()

if __name__ == "__main__":
    factory = TLSClientFactory()
    reactor.connectTCP('localhost', 8000, factory)
    reactor.run()
    </pre>

    <p><code>startTLS</code> is a transport method that gets passed a context.
    It is invoked at an agreed-upon time in the data reception method of the
    client and server protocols. The <code>ServerTLSContext</code> and
    <code>ClientTLSContext</code> classes used above inherit from the basic
    server and client context factories used in the earlier echo examples and
    illustrate two more ways of setting an SSL method.</p>

    <h2>Client authentication</h2>

    <p>Server and client-side changes to require client authentication fall
    largely under the dominion of pyOpenSSL, but few examples seem to exist on
    the web so for completeness a sample server and client are provided here.</p>

    <h3>Client-authenticating server</h3>

    <pre class="python">
from OpenSSL import SSL
from twisted.internet import ssl, reactor
from twisted.internet.protocol import Factory, Protocol

class Echo(Protocol):
    def dataReceived(self, data):
        self.transport.write(data)

def verifyCallback(connection, x509, errnum, errdepth, ok):
    if not ok:
        print 'invalid cert from subject:', x509.get_subject()
        return False
    else:
        print "Certs are fine"
    return True

if __name__ == '__main__':
    factory = Factory()
    factory.protocol = Echo

    myContextFactory = ssl.DefaultOpenSSLContextFactory(
        'keys/server.key', 'keys/server.crt'
        )

    ctx = myContextFactory.getContext()

    ctx.set_verify(
        SSL.VERIFY_PEER | SSL.VERIFY_FAIL_IF_NO_PEER_CERT,
        verifyCallback
        )

    # Since we have self-signed certs we have to explicitly
    # tell the server to trust them.
    ctx.load_verify_locations("keys/ca.pem")

    reactor.listenSSL(8000, factory, myContextFactory)
    reactor.run()
    </pre>

    <p>Use the <code>set_verify</code> method to set the verification mode for a
    context object and the verification callback. The mode is either
    <code>VERIFY_NONE</code> or <code>VERIFY_PEER</code>. If
    <code>VERIFY_PEER</code> is set, the mode can be augmented by
    <code>VERIFY_FAIL_IF_NO_PEER_CERT</code> and/or
    <code>VERIFY_CLIENT_ONCE</code>.</p>

    <p>The callback takes as its arguments a connection object, X509 object,
    error number, error depth, and return code. The purpose of the callback is
    to allow you to enforce additional restrictions on the verification. Thus,
    if the return code is False, you should return False; if the return code is
    True <i>and</i> further verification passes, return True.</p>


    <h3>Client with certificates</h3>

    <pre class="python">
from OpenSSL import SSL
from twisted.internet import ssl, reactor
from twisted.internet.protocol import ClientFactory, Protocol

class EchoClient(Protocol):
    def connectionMade(self):
        print "hello, world"
        self.transport.write("hello, world!")

    def dataReceived(self, data):
        print "Server said:", data
        self.transport.loseConnection()

class EchoClientFactory(ClientFactory):
    protocol = EchoClient

    def clientConnectionFailed(self, connector, reason):
        print "Connection failed - goodbye!"
        reactor.stop()

    def clientConnectionLost(self, connector, reason):
        print "Connection lost - goodbye!"
        reactor.stop()

class CtxFactory(ssl.ClientContextFactory):
    def getContext(self):
        self.method = SSL.SSLv23_METHOD
        ctx = ssl.ClientContextFactory.getContext(self)
        ctx.use_certificate_file('keys/client.crt')
        ctx.use_privatekey_file('keys/client.key')

        return ctx

if __name__ == '__main__':
    factory = EchoClientFactory()
    reactor.connectSSL('localhost', 8000, factory, CtxFactory())
    reactor.run()
    </pre>

    <h2>Other facilities</h2>

    <p><code class="API">twisted.protocols.amp</code> supports encrypted
    connections and exposes a <code>startTLS</code> method one can use or
    subclass. <code class="API">twisted.web</code> has built-in SSL support in
    its <code class="API" base="twisted.web">client</code>, <code class="API"
    base="twisted.web">http</code>, and <code class="API"
    base="twisted.web">xmlrpc</code> modules.</p>

    <h2>Conclusion</h2>

    <p>After reading through this tutorial, you should be able to: </p>
    <ul>
      <li>Use <code>listenSSL</code> and <code>connectSSL</code> to create servers and clients that use
      SSL</li>
      <li>Use <code>startTLS</code> to switch a channel from being unencrypted to using SSL
      mid-connection</li>
      <li>Add server and client support for client authentication</li>
    </ul>

  </body>
</html>
